Skip to content

docs: add custom backends guide for AI Grid and Chart - #6713

Open
tomivirkki wants to merge 7 commits into
mainfrom
docs/ai-custom-backends
Open

tomivirkki wants to merge 7 commits into
mainfrom
docs/ai-custom-backends

Conversation

@tomivirkki

Copy link
Copy Markdown
Member

Summary

  • The AI-powered Grid and Chart need a DatabaseProvider that runs SQL, and the docs did not say what to do when the data is behind a REST API, a service, or files. The new guide covers the two ways to add a SQL interface: an Apache Calcite adapter or a copy of the data in a database.
  • The guide stays on the Vaadin side of the integration (names and quoting, error relaying, threads, paging and counting) and links to Calcite's documentation for adapter configuration and development.
  • The Controllers page now documents the paging and counting methods of DatabaseProvider that the grid uses to load rows lazily, because the guide builds on them.

Fixes #6614

tomivirkki and others added 3 commits November 19, 2026 15:55
Describe executeQuery(String, QueryPage) and count(String), which the
AI-powered Grid uses to load rows lazily, and what their default
implementations do.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Show how to give the LLM a SQL view of a REST API, a service, or files:
through an Apache Calcite adapter or a copy of the data in a database,
and how to connect either one to a DatabaseProvider.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

@vaadin-review-bot vaadin-review-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the changes — left 4 comments.

Finding
💬 The guide never shows how the Calcite connection properties reach the calciteDataSource the provider is built from
⚠️ The grid already renders java.sql.Date and Timestamp, so the stated reason for converting them is wrong
📐 The page never says the Grid and Chart controllers require a commercial subscription
🗂️ Threading, concurrency and serialization facts about DatabaseProvider sit only in this guide, not in the reference

* Convert JDBC date values to [classname]`LocalDate` and timestamp values to [classname]`LocalDateTime` for the grid's date renderers.
* Relay useful SQL parse and validation errors in a [classname]`ToolException` so the LLM can correct its query. Calcite reports them as a [classname]`SqlParseException` or a [classname]`CalciteContextException` in the cause chain of the [classname]`SQLException`. Keep row values and backend details out of those messages, and use a generic message for other failures. The message of the [classname]`SQLException` itself can include the error text of your backend, so don't relay it as it is.

For example, these connection properties accommodate the names and the SQL that the LLM and the grid may use. Apply them when creating the Calcite connection alongside the adapter's configuration:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💬 The guide never shows how the Calcite connection properties reach the calciteDataSource the provider is built from

The page says "Apply them when creating the Calcite connection alongside the adapter's configuration" and shows a Properties object, but the next section jumps to new CalciteDatabaseProvider(calciteDataSource) with "a DataSource configured for Calcite". Calcite has no DataSource of its own, so the reader is left to work out the bridge: DriverManager.getConnection("jdbc:calcite:...", properties), the same settings as connect-string parameters in the JDBC URL, or a pool's dataSourceProperties.

The intro scopes adapter configuration out to Calcite's documentation, but this step is the Vaadin-side wiring the guide claims to own. One sentence naming the URL form, or a line that creates the connection from the properties, closes the gap.

custom-backends.adoc:96 · clarity

* LLMs often use SQL keywords such as `value` or `year` as column aliases. If your parser configuration allows it, add `calcite-babel` and select Calcite's Babel parser to accept more such names.
* LLMs also group by a column alias or position and write `!=`, which Calcite rejects by default. Calcite also pads the string literals of a `CASE` or `UNION` with spaces to the same length, so such a label no longer equals a column value. The `conformance=MYSQL_5` setting accepts that SQL and doesn't pad the literals.
* Remove a trailing semicolon before running a query. Calcite rejects it, and the chart passes the LLM's SQL to [methodname]`executeQuery(String sql)` unchanged.
* Convert JDBC date values to [classname]`LocalDate` and timestamp values to [classname]`LocalDateTime` for the grid's date renderers.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ The grid already renders java.sql.Date and Timestamp, so the stated reason for converting them is wrong

Convert JDBC date values to LocalDate and timestamp values to LocalDateTime for the grid's date renderers.

GridRenderer.addColumn() picks LocalDateRenderer for java.sql.Date and LocalDateTimeRenderer for Timestamp, converting them itself (vaadin-ai-extensions-flow/.../grid/GridRenderer.java:105-112 and :186-203); DefaultDataConverter handles both types for the chart. The JDBC provider on the Controllers page returns rs.getObject(i) raw and works, so as written this bullet suggests that example is incomplete.

If Calcite returns something else for DATE and TIMESTAMP columns, say that — I could not check Calcite's return types here. Otherwise the bullet can go.

custom-backends.adoc:93 · accuracy


:preview-feature: AI integration features
:feature-flag: com.vaadin.experimental.aiComponents
include::{articles}/_preview-banner.adoc[opts=optional]

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 The page never says the Grid and Chart controllers require a commercial subscription

The whole guide is about feeding GridAIController and ChartAIController, which are part of the commercial vaadin-ai-extensions-flow module. The page carries only the preview banner.

guidelines/versions-and-lifecycle.md: "Pages about a commercial component or tool include the commercial banner right after the page title, with the product named in the commercial-feature attribute." The AI-Powered Grid and Chart pages both do this, and building-apps/agentic-development/mcp/self-hosting/index.adoc shows the banner is used in Building Apps too. A reader can otherwise build the adapter, the provider and the refresh job before learning a subscription is needed.

custom-backends.adoc:15 · conventions


A provider created in the view can keep backend credentials and cached data specific to one user. Share a provider between users only when every user may see the same data. If the provider keeps a JDBC connection, keep it `transient` and recreate it after session deserialization. Ensure the provider's other fields are serializable or can be restored as well. The provider can be called concurrently, for example when the grid loads a page while the LLM's next query is validated.

The controller also calls the provider from background threads when it validates the LLM's SQL. This happens with a streaming LLM provider or <<{articles}/flow/ai-support/llm-providers#background-execution,background execution>>. [methodname]`VaadinSession.getCurrent()` and [methodname]`UI.getCurrent()` return `null` there, and Spring Security's [classname]`SecurityContextHolder` has no authentication by default. Capture the user's credentials when the view creates the provider or its backend client, instead of looking them up during a query.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗂️ Threading, concurrency and serialization facts about DatabaseProvider sit only in this guide, not in the reference

Three facts in Use the Provider hold for every DatabaseProvider, not just a custom backend:

  • the controller calls the provider from background threads during validation, where UI.getCurrent() and the Spring SecurityContext are absent
  • the provider can be called concurrently
  • a JDBC connection field should be transient

Would these belong in the Database Provider section of articles/flow/ai-support/controllers.adoc, with this guide linking to them? CONVENTIONS.md: "Keep a reference page complete on its own", and guidelines/information-architecture.md: "When it lacks a detail, add the detail to the reference." A reader writing a plain JDBC provider has no reason to open a guide about Calcite.

custom-backends.adoc:146 · placement

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Preview Deployment

This PR has been deployed for preview.

URL: https://docs-preview-pr-6713.fly.dev

Changed pages

Added content is highlighted in green; removed content is marked in red on each page.

Built from d08717e

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document custom backends for the AI-powered Grid and Chart

2 participants